Signing in users with OAuth v2

To enable user sign-in using OAuth 2.0, follow these steps:

  1. From the Flow Palette, Dialog section, drag the Oauth 2.0 Sign in step and drop it within the flow where you want to perform the OAuth v2 sign in.

  2. Provide a flow step name.
  3. From the Connection Code field, select the connector app you created for OAuth v2 authorization.
  4. In the General section, tap on Get user identity.

    5. Note:  For DRUID versions earlier than 8.15, enter the sign-in link in the Step message field using the following format: [[ChatUser]].OauthAccessURL. For example: "Sign in to Google using this link: [[ChatUser]].OauthAccessURL"
  5. In the Metadata section, tap on Block user input. By default, the sign-in step is rendered as a hero card.
  6. Configure the hero card with the following buttons:
    • Sign In - Set the value to: [[ChatUser]].OauthAccessURL.
    • Cancel - Set the value to: cancel.

  7. Save the step to apply the changes.

Continue designing your flow with actions the assistant should perform on user’s behalf after getting user’s authorization.

Note:   You can use the authorization URL in any other application and channel; this is why you might need to white list the domain of this application (the domain of the Redirect URL set on the OAuth2 app).

When the OAuth 2.0 Sign In step runs, the user's identity metadata will be stored in the [[ChatUser]] entity. This mapping is based on the response configuration in the Get User Identity connector action.

Important!  The SSO Sign step DOES NOT automatically authenticate the user in the conversation!

After this step, continue with DRUID-specific authentication using actions such as: SaveIdentifiedUser and SaveAuthenticatedUser. These can be configured either in the next step of the flow or in the PostActions section of the SSO Sign In step.

At runtime, when the user clicks the Sign in button/link, DRUID redirects the user to a DRUID hosted page (the login/consent page at the WEB API service). Example:

After the user confirms the authorization, the first special action in the OAuth App is automatically invoked and the authorization process completes, meaning that the access token will be saved in the conversation context and used on any integration which consumes that specific OAuth App. DRUID virtual assistant will further perform the actions on user’s behalf as set in the conversational flow.

signing in users with OAuth v2 best practices

Use these best practices for authoring the flow where you want to perform the OAuth v2 sign in to ensure that the access token used to authorize server-to-server API calls is generated after expiry:

  • Set condition to execute the Oauth 2.0 Sign in flow step (the one you configured at step 4 above) only if [[ChatUser]].SSOToken == null.

  • After executing the Oauth 2.0 Sign in flow step, run the integration.

  • Handle the exceptions when the access token expires. For that, on the integration step, in the Metadata section, tap on Exception handler.

    Add an action step for integration exception that is executed if [[SystemError]].IsException == true. The Oauth 2.0 Sign in flow step is executed if [[SystemError]].Code=="401".

  • Continue the conversation if no exceptions are thrown during the integration execution.